package module.StoreService;

import common.model.Entity.StoreEntity.OrderItem;
import network.protocol.Response;
import java.util.List;
import java.util.Optional;

/**
 * {@code OrderItemService} 定义了订单项（OrderItem）相关的业务操作接口。
 * <p>
 * 主要提供以下功能：
 * <ul>
 *     <li>根据 ID 或订单 ID 查询订单项</li>
 *     <li>获取所有订单项</li>
 *     <li>创建、批量创建、更新、逻辑删除订单项</li>
 *     <li>根据订单 ID 删除订单项</li>
 *     <li>统计订单项数量</li>
 *     <li>计算订单总金额</li>
 * </ul>
 * <p>
 * 所有方法均返回统一封装的 {@link Response} 对象，
 * 调用方可根据该对象判断操作成功与否并获取相关数据。
 */
public interface OrderItemService {

    /**
     * 根据订单项 ID 获取订单项。
     *
     * @param id 订单项的唯一标识
     * @return 包含订单项对象的响应；
     *         如果不存在，则返回 {@link Optional#empty()}
     */
    Response<Optional<OrderItem>> getOrderItemById(long id);

    /**
     * 根据订单 ID 获取该订单下的所有订单项。
     *
     * @param orderId 订单的唯一标识
     * @return 包含订单项列表的响应对象；
     *         如果没有订单项，则返回空列表
     */
    Response<List<OrderItem>> getOrderItemsByOrderId(long orderId);

    /**
     * 获取系统中所有订单项。
     *
     * @return 包含订单项列表的响应对象；
     *         如果没有订单项，则返回空列表
     */
    Response<List<OrderItem>> getAllOrderItems();

    /**
     * 创建新的订单项。
     *
     * @param orderItem 订单项实体对象，包含必要的订单信息
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createOrderItem(OrderItem orderItem);

    /**
     * 更新订单项信息。
     *
     * @param orderItem 订单项实体对象，必须包含有效的 ID
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> updateOrderItem(OrderItem orderItem);

    /**
     * 删除订单项（逻辑删除，不会物理移除数据）。
     *
     * @param id 订单项的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> deleteOrderItem(long id);

    /**
     * 根据订单 ID 删除该订单下的所有订单项。
     *
     * @param orderId 订单的唯一标识
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> deleteOrderItemsByOrderId(long orderId);

    /**
     * 获取系统中订单项的总数量。
     *
     * @return 包含订单项总数的响应对象
     */
    Response<Long> getOrderItemCount();

    /**
     * 计算指定订单的总金额。
     *
     * @param orderId 订单的唯一标识
     * @return 包含订单总金额的响应对象
     */
    Response<Double> calculateOrderTotal(long orderId);

    /**
     * 批量创建订单项。
     *
     * @param orderItems 订单项实体对象列表
     * @return 操作是否成功的响应对象
     */
    Response<Boolean> createOrderItems(List<OrderItem> orderItems);
}
